package org.ciallo.easytokencore.annotation.handler;

import java.lang.annotation.Annotation;
import java.lang.reflect.Method;

/**
 * Easy-Token 注解处理器核心接口
 *
 * <p>设计目的：</p>
 * <ul>
 *   <li>定义注解处理器的标准接口规范</li>
 *   <li>支持自定义注解的扩展处理</li>
 *   <li>提供类型安全的注解处理方法</li>
 *   <li>统一处理器生命周期管理</li>
 * </ul>
 *
 * <p>生命周期阶段：</p>
 * <ol>
 *   <li>preHandle: 方法执行前</li>
 *   <li>postHandle: 方法执行后，视图渲染前</li>
 *   <li>afterCompletion: 请求完成后</li>
 * </ol>
 *
 * <p>实现规范：</p>
 * <ol>
 *   <li>通过getHandlerAnnotationClass()声明处理的注解类型</li>
 *   <li>实现三个阶段的处理方法</li>
 *   <li>默认方法已处理类型转换</li>
 * </ol>
 *
 * <p>实现示例：</p>
 * <pre>
 * {@code
 * public class MyHandler implements EasyAnnotationHandlerInterface<MyAnnotation> {
 *     public Class<MyAnnotation> getHandlerAnnotationClass() {
 *         return MyAnnotation.class;
 *     }
 *
 *     public void checkMethodPostHandle(MyAnnotation at, Method method) {
 *         // 具体处理逻辑
 *     }
 *     // 其他方法实现...
 * }
 * }
 * </pre>
 *
 * @param <T> 处理的注解类型，必须继承自java.lang.annotation.Annotation
 * @Description: Easy-Token 注解处理器核心接口
 * @Author: Jukomu
 * @Package: org.ciallo.easytokencore.annotation.handler
 * @Project: easy-token-demo
 * @Version: 1.1.0
 * @name: EasyAnnotationHandlerInterface
 * @Date: 2025-05-17
 * @Filename: EasyAnnotationHandlerInterface
 * @see java.lang.annotation.Annotation
 */
public interface EasyAnnotationHandlerInterface<T extends Annotation> {
    /**
     * 获取所要处理的注解类型
     *
     * @return /
     */
    Class<T> getHandlerAnnotationClass();

    /**
     * 请求方法处理前所需要执行的校验方法
     *
     * @param at     注解对象
     * @param method 被标注的注解的方法引用
     */
    @SuppressWarnings("unchecked")
    default void checkPreHandle(Annotation at, Method method) {
        checkMethodPreHandle((T) at, method);
    }


    /**
     * 请求方法处理完成后、视图渲染之前所需要执行的校验方法
     *
     * @param at     注解对象
     * @param method 被标注的注解的方法引用
     */
    @SuppressWarnings("unchecked")
    default void checkPostHandle(Annotation at, Method method) {
        checkMethodPostHandle((T) at, method);
    }


    /**
     * 在整个请求完成时所需要执行的校验方法
     *
     * @param at     注解对象
     * @param method 被标注的注解的方法引用
     */
    @SuppressWarnings("unchecked")
    default void checkAfterCompletion(Annotation at, Method method) {
        checkMethodAfterCompletion((T) at, method);
    }

    /**
     * 所需要执行的校验方法（转换类型后）
     *
     * @param at     注解对象
     * @param method 被标注的注解的方法引用
     */
    void checkMethodPreHandle(T at, Method method);

    /**
     * 所需要执行的校验方法（转换类型后）
     *
     * @param at     注解对象
     * @param method 被标注的注解的方法引用
     */
    void checkMethodPostHandle(T at, Method method);

    /**
     * 所需要执行的校验方法（转换类型后）
     *
     * @param at     注解对象
     * @param method 被标注的注解的方法引用
     */
    void checkMethodAfterCompletion(T at, Method method);
}
